home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem2.asc < prev    next >
Text File  |  1987-10-10  |  20KB  |  417 lines
  1.                       ** Professional GEM **
  2.                            by Tim Oren
  3.  
  4.                      Topic: Windows, part II
  5.                              10/21/85
  6.  
  7.  
  8.                             EXCELSIOR!
  9.  
  10.   In this installment, we continue the exploration of GEM's window
  11. manager by finding out how to process the messages received by an
  12. application when it has a window defined on the screen.
  13.  
  14.   Also, beginning with this column, sample C code demonstrating the
  15. techniques discussed will be available on SIG*ATARI in DL5.  This
  16. will allow you to download the code without interference by the CIS
  17. text-formatter used by ANTIC ONLINE output.
  18.  
  19.   The file for this column is GEMCL2.XMO.  All references  to non-GEM
  20. routines in this column refer to this file.  Please note that  these
  21. files will not contain entire programs.  Instead, they consist of
  22. small pieces of utility code which you may copy and modify in your
  23. own  programs.
  24.  
  25.                         REDRAWING WINDOWS
  26.  
  27.   One of the most misunderstood parts of GEM is the correct method for
  28. drawing within a window.  Most requests for redrawing are generated
  29. by the GEM system, and arrive as messages (read with evnt_multi)
  30. which contain the handle of the window, and the screen rectangle
  31. which is  "dirty" and needs to be redrawn.
  32.  
  33.   Screen areas may become dirty as a result of windows being closed,
  34. sized down, or moved, thus "exposing" an area underneath.  The
  35. completion of  a dialog, or closing of a desk accessory may also free
  36. up a screen area which needs to be redrawn.  When GEM detects the
  37. presence of a dirty rectangle,  it checks its list of open windows,
  38. and sends the application a redraw message  for each of its windows
  39. which intersects the dirty area.
  40.  
  41.                           CAVEAT EMPTOR
  42.  
  43.   GEM does not "clip" the rectangle which it sends to  the application;
  44. that is, the rectangle may not lie entirely within the  portion of
  45. the window which is exposed on the screen.  It is the job of the
  46. application to determine in what portion of the rectangle it may
  47. safely draw.   This is done by examining the "rectangle list"
  48. associated with the window.
  49.  
  50.   A rectangle list is maintained by GEM for each active window.  It
  51. contains the portions of the window's interior which are exposed,
  52. i.e., topmost, on the screen and within which the app may draw.
  53.  
  54.   Let's consider an example to make this clear.  Suppose an app has
  55. opened two windows, and there are no desk accessory windows open. The
  56. window which is topmost will  always have only one rectangle in its
  57. list.  If the two are separate on the  screen, then the second window
  58. will also have one rectangle.  If they overlap,  then the top window
  59. will "break" the rectangle of the bottom one.  If the  overlap is at
  60. a corner, two rectangles will be generated for the bottom window.  If
  61. the overlap is on a side only, then three rectangles are required to
  62. cover  the exposed portion of the bottom window.  Finally, if the
  63. first window is  entirely within the second, it requires four
  64. rectangles in the list to tile the second window.
  65.  
  66.   Try working out a few rectangle examples with pencil and paper to
  67. get the feel of it.  You will see that the possible combinations with
  68. more  than two windows are enormous.  This, by the way, is the reason
  69. that GEM does  not send one message for each rectangle on the list:
  70. With multiple windows,  the number of messages generated would
  71. quickly fill up the application's message queue.
  72.  
  73.   Finally, note that every app MUST use this method, even if it only
  74. uses a single window, because there may be desk accessories with
  75. their own  windows in the system at the same time.  If you do not use
  76. the rectangle lists, you may overwrite an accessory's window.
  77.  
  78.                           INTO THE BITS
  79.  
  80.   First, we should note that the message type for a  redraw request is
  81. WM_REDRAW, which is stored in msg[0], the first location of the
  82. message returned by evnt_multi.  The window handle is stored in
  83. msg[3].  These locations are the same for all of the message types
  84. being discuss.  The rectangle which needs to be redrawn is stored in
  85. msg[4] through msg[7].
  86.  
  87.   Now let's examine the sample redraw code in more detail. The redraw
  88. loop is bracketed with mouse off and mouse on calls.  If you forget
  89. to do  this, the mouse pointer will be over-written if it is within
  90. the window and  the next movement of the mouse will leave a
  91. rectangular blotch on the screen  as a piece of the "old" screen is
  92. incorrectly restored.
  93.  
  94.   The other necessary step is to set the window update flag.  This
  95. prevents the menu manager from dropping a menu on top of the screen
  96. portion being redrawn.  You must release this flag at the end of the
  97. redraw, or the you will be unable to use any menus afterwards.
  98.  
  99.   The window rectangles are retrieved using a get-first, get-next
  100. scheme which will be familiar if you have used the GEM DOS or PC-DOS
  101. wildcard file calls.  The end of the rectangle list has been reached
  102. when both the width and height returned are zero.  Since some part of
  103. a  window might be off-screen (unless you have clamped its position -
  104. see below), the retrieved rectangle is intersected with the desktop's
  105. area,  and then with the screen area for which a redraw was
  106. requested.
  107.  
  108.   Now you have the particular area of the screen in which it is  legal
  109. to draw.  Unless there is only one window in your application, you
  110. will have to test the handle in the redraw request to figure out what
  111. to  put in the rectangle.
  112.  
  113.   Depending on the app, you may be drawing an AES  object tree, or
  114. executing VDI calls, or some combination of the two.  In  the AES
  115. case, the computed rectangle is used to specify the bounds of the
  116. objc_draw.  For VDI work, the rectangle is used to set the clipping
  117. area before executing the VDI calls.
  118.  
  119.                         A SMALL CONFESSION
  120.  
  121.   At the beginning of this discussion, I  deliberately omitted one
  122. class of redraws: those initiated by the application  itself.
  123.  
  124.   In some cases a part of the screen must be redrawn immediately to
  125. give feedback to the user following a keystroke, button, or mouse
  126. action.   In these cases, the application could call do_redraw
  127. directly, without  waiting for a message.
  128.  
  129.   The only time you can bypass do_redraw, and draw  without walking the
  130. rectangle list, is when you can be sure that the target  window is on
  131. top, and that the figure being drawn is entirely contained  within
  132. it.
  133.  
  134.   In many cases, however, an application initiated redraw happens
  135. because of a computed change, for instance, a spreadsheet update, and
  136. its timing is not crucial.  In this instance, you may wish to have
  137. the  app send ITSELF a redraw request.
  138.  
  139.   The main advantage of this approach  is that the AES is smart enough
  140. to see if there is already a redraw request for the same window in
  141. the queue, and, if so, to merge the requests by  doing a union of
  142. their rectangles.  In this fashion, the "blinky" appearance of
  143. multiple redraws is avoided, without the need to include logic for
  144. merging redraws within the program.
  145.  
  146.   A utility routine for sending the "self-redraw" is included in the
  147. down-load for this article.
  148.  
  149.                      WINDOW CONTROL REQUESTS
  150.  
  151.   An application is notified by the AES, via the message system, when
  152. the user manipulates one of the window control points.  Remember that
  153. you must have specified each control point when the window was
  154. created, or will not receive the associated control message.
  155.  
  156.   The most important thing to understand about window control is that
  157. the change which the user requested does not take place until the
  158. application forwards it to the AES.  While this makes for a little
  159. extra work,  it gives the program a chance to intervene and validate
  160. or modify the request to suit.
  161.  
  162.   A second thing to keep in mind is that not all window updates cause a
  163. redraw request to be generated for the window, because the AES
  164. attempts to save time with raster moves on the screen.
  165.  
  166.   Now let's look at each window control request in detail.  The
  167. message code for a window move is WM_MOVED.  If you are willing to
  168. accept  any such request, just do:
  169.  
  170.   wind_set(wh, WF_CXYWH, msg[4], msg[5], msg[6], msg[7]);
  171.  
  172.   (Remember that wh, the window handle, is always in